From b90d773c2899c3503c1f2ca1d6383f9a44f36c0d Mon Sep 17 00:00:00 2001
From: Havoc Pennington <hp@redhat.com>
Date: Wed, 1 Nov 2000 16:01:17 +0000
Subject: [PATCH] Check in these docs, I seem to have written them a while ago
 then

2000-11-01  Havoc Pennington  <hp@redhat.com>

	* gtk/tmpl/gtkmessagedialog.sgml: Check in these docs, I seem to
	have written them a while ago then forgotten about them.
---
 docs/reference/ChangeLog                      |  5 ++
 docs/reference/gtk/tmpl/gtkmessagedialog.sgml | 72 +++++++++++++++----
 2 files changed, 64 insertions(+), 13 deletions(-)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 160d5e9c95..5c8e9ae41c 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2000-11-01  Havoc Pennington  <hp@redhat.com>
+
+	* gtk/tmpl/gtkmessagedialog.sgml: Check in these docs, I seem to
+	have written them a while ago then forgotten about them.
+
 2000-11-01  Havoc Pennington  <hp@pobox.com>
 
 	* gtk/gtk-sections.txt: Add new label functions
diff --git a/docs/reference/gtk/tmpl/gtkmessagedialog.sgml b/docs/reference/gtk/tmpl/gtkmessagedialog.sgml
index fe3f82f693..f41e6bc015 100644
--- a/docs/reference/gtk/tmpl/gtkmessagedialog.sgml
+++ b/docs/reference/gtk/tmpl/gtkmessagedialog.sgml
@@ -3,15 +3,59 @@ GtkMessageDialog
 
 <!-- ##### SECTION Short_Description ##### -->
 
+convenient message window
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+#GtkMessageDialog presents a dialog with an image representing the type of 
+message (Error, Question, etc.) alongside some message text. It's simply a 
+convenience widget; you could construct the equivalent of #GtkMessageDialog 
+from #GtkDialog without too much effort, but #GtkMessageDialog saves typing.
+</para>
 
+<para>
+The easiest way to do a modal message dialog is to use gtk_dialog_run(), though
+you can also pass in the GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically
+makes the dialog modal and waits for the user to respond to it. gtk_dialog_run()
+returns when any dialog button is clicked.
+<example>
+<title>Modal #GtkMessageDialog</title>
+<programlisting>
+ dialog = gtk_message_dialog_new (main_application_window,
+                                  GTK_DIALOG_DESTROY_WITH_PARENT,
+                                  GTK_MESSAGE_ERROR,
+                                  GTK_BUTTONS_CLOSE,
+                                  "Error loading file '%s': %s",
+                                  filename, g_strerror (errno));
+ gtk_dialog_run (GTK_DIALOG (dialog));
+ gtk_widget_destroy (dialog);
+</programlisting>
+</example>
 </para>
 
-<!-- ##### SECTION See_Also ##### -->
 <para>
+You might do a non-modal #GtkMessageDialog as follows:
+<example>
+<title>Non-modal #GtkMessageDialog</title>
+<programlisting>
+ dialog = gtk_message_dialog_new (main_application_window,
+                                  GTK_DIALOG_DESTROY_WITH_PARENT,
+                                  GTK_MESSAGE_ERROR,
+                                  GTK_BUTTONS_CLOSE,
+                                  "Error loading file '%s': %s",
+                                  filename, g_strerror (errno));
+
+ /* Destroy the dialog when the user responds to it (e.g. clicks a button) */
+ gtk_signal_connect_object (GTK_OBJECT (dialog), "response",
+                            GTK_SIGNAL_FUNC (gtk_widget_destroy),
+                            GTK_OBJECT (dialog));
+</programlisting>
+</example>
+</para>
 
+<!-- ##### SECTION See_Also ##### -->
+<para>
+#GtkDialog
 </para>
 
 <!-- ##### STRUCT GtkMessageDialog ##### -->
@@ -22,25 +66,27 @@ GtkMessageDialog
 
 <!-- ##### ENUM GtkMessageType ##### -->
 <para>
-
+The type of message being displayed in the dialog.
 </para>
 
-@GTK_MESSAGE_INFO: 
-@GTK_MESSAGE_WARNING: 
-@GTK_MESSAGE_QUESTION: 
-@GTK_MESSAGE_ERROR: 
+@GTK_MESSAGE_INFO: Informational message
+@GTK_MESSAGE_WARNING: Nonfatal warning message
+@GTK_MESSAGE_QUESTION: Question requiring a choice
+@GTK_MESSAGE_ERROR: Fatal error message
 
 <!-- ##### ENUM GtkButtonsType ##### -->
 <para>
-
+Prebuilt sets of buttons for the dialog. If 
+none of these choices are appropriate, simply use GTK_BUTTONS_NONE
+then call gtk_dialog_add_buttons().
 </para>
 
-@GTK_BUTTONS_NONE: 
-@GTK_BUTTONS_OK: 
-@GTK_BUTTONS_CLOSE: 
-@GTK_BUTTONS_CANCEL: 
-@GTK_BUTTONS_YES_NO: 
-@GTK_BUTTONS_OK_CANCEL: 
+@GTK_BUTTONS_NONE: no buttons at all
+@GTK_BUTTONS_OK: an OK button
+@GTK_BUTTONS_CLOSE: a Close button
+@GTK_BUTTONS_CANCEL: a Cancel button
+@GTK_BUTTONS_YES_NO: Yes and No buttons
+@GTK_BUTTONS_OK_CANCEL: OK and Cancel buttons
 
 <!-- ##### FUNCTION gtk_message_dialog_new ##### -->
 <para>
-- 
2.30.2